Crate alloy_sol_types

source ·
Expand description

Solidity type modeling and ABI coding implementation.

This crate provides tools for expressing Solidity types in Rust, and for encoding these representations into ABI blobs suitable for smart contract processing. In other words, you can represent your smart contract args in native Rust, easily encode them to pass to a smart contract, and easily decode the smart contract return values.

We do this by representing Solidity types in rust via the SolType trait. This trait maps Solidity types to Rust types via the associated SolType::RustType.

Each SolType also has an associated SolType::TokenType. This is the intermediate representation of the data suitable for ABI encoding. The ABI encode and decode methods operate on objects implementing TokenType.

use alloy_sol_types::{SolType, sol_data::*};
// Represent a Solidity type in rust
type MySolType = FixedArray<Bool, 2>;

let data = [true, false];
let validate = true;

// SolTypes expose their Solidity name :)
assert_eq!(&MySolType::sol_type_name(), "bool[2]");

// SolTypes are used to transform Rust into ABI blobs, and back.
let encoded: Vec<u8> = MySolType::encode(&data);
let decoded: [bool; 2] = MySolType::decode(&encoded, validate)?;
assert_eq!(data, decoded);

sol!

The sol! procedural macro provides a convenient way to define custom SolTypes and reference primitive ones. See its documentation for details on how to use it.

SolStruct

The SolStruct trait primarily provides EIP-712 signing support.

// `sol!` allows you to define struct types!
// You can just paste Solidity into the macro and it should work :)
sol! {
    struct MyStruct {
        uint256 a;
        bytes32 b;
        address[] c;
    }
}

sol! {
    struct MyStruct2 {
        MyStruct a;
        bytes32 b;
        address[] c;
    }
}

// All structs generated with `sol!` implement `crate::SolType` &
// `crate::SolStruct`. This means you get eip-712 signing for freeeeee
let my_struct = MyStruct {
    a: U256::from(1),
    b: [0; 32],
    c: vec![Default::default()],
};

// The `eip712_domain` macro lets you easily define an EIP-712 domain
// object :)
let my_domain = alloy_sol_types::eip712_domain!(
   name: "MyDomain",
   version: "1",
);

// Because all the hard work is done by the `sol!` macro, EIP-712 is as easy
// as calling `eip712_signing_hash` with your domain
let signing_hash = my_struct.eip712_signing_hash(&my_domain);

sol! User-defined Value Types

Support for user-defined value types is new! These are currently implemented as wrapper types. Watch this space for more features!

// We also also support Solidity value types
sol! {
    type MyValueType is uint256;
}

// UDTs are encoded as their underlying type
let mvt = MyValueType::from(U256::from(1));
assert_eq!(
    mvt.encode_single(),
    sol_data::Uint::<256>::encode_single(&U256::from(1))
);

Tokenization/Detokenization

The process of converting from a Rust type to a to an abi token is called “Tokenization”. Typical users will not access tokenizaiton directly. Power users should use the SolType::tokenize() and SolType::detokenize() methods.

When implementing your own SolType, a variety of From impls have been provided on the token structs to aid in converting from Rust data to tokens.

Encoding/Decoding

The process of converting from a TokenType to a serialized ABI blob is called “Encoding”. It is the reciprocal of decoding.

ABI encoding and decoding operates on sequences of tokens.

The SolType encoding and decoding methods operate on Rust types. We recommend users use them wherever possible. We do not recommend that users interact with Tokens, except when implementing their own SolType.

Re-exports

  • pub use alloy_sol_macro::sol;

Modules

Macros

  • define_udt
    Define a Solidity user-defined value type.
  • eip712_domain
    Convenience macro to instantiate an EIP-712 domain.

Structs

  • Eip712Domain
    Eip712 Domain attributes used in determining the domain separator; Unused fields are left out of the struct type.
  • Panic
    A Solidity panic.
  • Revert
    Represents a standard Solidity revert. These are thrown by require(condition, reason) statements in Solidity.
  • Selectors
    Iterator over the function or error selectors of a SolInterface type.

Enums

Traits

  • Encodable
    An encodable is any type that may be encoded via a given SolType.
  • EventTopic
    A Solidity event topic.
  • SolCall
    Solidity call (a tuple with a selector).
  • SolEnum
    Solidity enum. This is always a wrapper around a u8.
  • SolError
    Solidity Error (a tuple with a selector)
  • SolEvent
    Solidity event.
  • SolInterface
    A collection of ABI-encoded call-like types. This currently includes SolCall and SolError.
  • SolStruct
    A Solidity Struct.
  • SolType
    A Solidity Type, for ABI encoding and decoding
  • TokenType
    Abi-Encoding Tokens. This is a sealed trait. It contains the type information necessary to encode & decode data. Tokens are an intermediate state between abi-encoded blobs, and rust types.
  • TopicList
    A TopicList represents the topics of a Solidity event.

Functions

  • decode
    Decodes ABI compliant vector of bytes into vector of tokens described by types param.
  • decode_params
    Decode top-level function args. Encodes as params if T is a tuple. Otherwise, wraps in a tuple and decodes.
  • decode_single
    Decode a single token.
  • encode
    ABI-encode a token sequence.
  • encode_params
    Encode a tuple as ABI function params, suitable for passing to a function.
  • encode_single
    ABI-encode a single token.

Type Definitions